Add an example to the readme? #2067
Conversation
This comment was marked as off-topic.
This comment was marked as off-topic.
README.md
Outdated
|
|
||
| [](https://fluxml.github.io/Flux.jl/stable/) [](https://julialang.org/slack/) [](https://github.com/SciML/ColPrac) [](https://doi.org/10.21105/joss.00602) | ||
|
|
||
| [![][action-img]][action-url] [![][codecov-img]][codecov-url] |
There was a problem hiding this comment.
Moved because these badges wrapped to 2 lines, and seemed to be in random order. This puts the CI ones on 2nd line, and centres them below the logo.
There was a problem hiding this comment.
I think FluxML projects should also include the "number of downloads" badge in their READMEs -
... and so on
There was a problem hiding this comment.
Could do, 88k sounds like a lot...
This comment was marked as off-topic.
This comment was marked as off-topic.
README.md
Outdated
| [](https://fluxml.github.io/Flux.jl/stable/) [](https://julialang.org/slack/) [](https://github.com/SciML/ColPrac) [](https://doi.org/10.21105/joss.00602) | ||
| <br/> | ||
| [![][action-img]][action-url] [![][codecov-img]][codecov-url] |
There was a problem hiding this comment.
Also, it might be better to arrange these badges in a table? Something like this -
| Type | Badge/Status |
|---|---|
| CI |    |
| Documentation |   |
| Community |    |
| DOI and version |   |
But this would take more vertical space
There was a problem hiding this comment.
This is more logically organised. But I'm not sure these badges are really so valuable. Knowing to click the blue button is a quick way to get to the docs on an unknown package, but perhaps we should trim some of the others.
|
The example feels too smart, but on the other hand it could be more catchy than a simpler mnist example. |
|
I wondered about MNIST, but I think it'll end up a fair bit longer... and more of the code dealing with loading data etc, rather than core Flux + basic Julia stuff? Could do linear regression pretty compactly, but that seems less illustrative. I do think it should be short. Having a long nicely explained example means it starts competing with the docs as an alternative way to learn, and we already have too many paths. Just a minimal thing you can copy-paste on day 1 & see that everything is installed and working. |
this is a slightly weird feature of our API... and since we also call logitcrossentropy a loss function, perhaps we should emphasize that loss(x,y) is a new thing just for this model, not a function for all time.
| model = Chain(Dense(2 => 3, sigmoid), BatchNorm(3), Dense(3 => 2)) |> gpu | ||
| optim = Adam(0.1, (0.7, 0.95)) | ||
| mloss(x, y) = Flux.logitcrossentropy(model(x), y) # closes over model | ||
|
|
||
| Flux.train!(mloss, Flux.params(model), data, optim) # updates model & optim |
There was a problem hiding this comment.
BTW, this business of defining a loss which, unlike what Flux.Losses calls a loss, closes over the model, was pretty confusing to me when I first tried Flux.
train! needs two different objects with implicit references to the model (and optim ends up with them), but does not seem to see the model itself? That's pretty weird.
IMO we should define crossentropy(m, x, y) = crossentropy(m(x), y) globally, and make Flux 0.14 do this, which is much less confusing:
model = Chain(Dense(2 => 3, sigmoid), BatchNorm(3), Dense(3 => 2)) |> gpu
optim = Flux.setup(model, Adam(0.1, (0.7, 0.95))) # stores Adam's momenta
Flux.train!(Flux.logitcrossentropy, model, data, optim) # updates model & optim
There was a problem hiding this comment.
This seems the way forward to move train! away from Params.
This proposes to add a very simple Flux model to the readme. Almost the simplest thing I could think of, which actually works.
It's nice to see code right away. I guess it won't make sense if you've never seen a neural network, but if you've ever tried any demo elsewhere, this should look familiar, and point out the main features. Including (I hope) that batch dims are last, that the model is a mutable object, how to move to GPU, what arguments
train!needs (and in what order).Without BatchNorm this works 90% of the time, with default Adam() too just 80%. So the post-1969 details are doing something.
On Julia 1.7+, just pasting this in will install everything including CUDA.
Maybe it should say that. I didn't want to put too many words.Now it does.